Skip to content

feat(layer-4): SDK additive — live_fallback_mode + parent_agent_id kwargs (cueapi #823 + #824 parity)#44

Merged
mikemolinet merged 1 commit into
mainfrom
feat/sdk-live-fallback-mode-and-parent-agent-id
May 13, 2026
Merged

feat(layer-4): SDK additive — live_fallback_mode + parent_agent_id kwargs (cueapi #823 + #824 parity)#44
mikemolinet merged 1 commit into
mainfrom
feat/sdk-live-fallback-mode-and-parent-agent-id

Conversation

@mikemolinet
Copy link
Copy Markdown
Collaborator

Summary

Agent-id-split refactor Layer 4 OSS-SDK additives — live_fallback_mode kwarg on MessagesResource.send() + parent_agent_id kwarg on AgentsResource.create(). Both purely additive; wire format identical when omitted.

Context

Hosted cueapi shipped the agent-id-split substrate refactor today: PR-A #823 schema + PR-B #824 router + PR-C #825 migration + #828 hotfix + PR-D #830 orphan-binding. Empirically proven on prod 2026-05-12 ~23:56Z (full bulletproof closed at msg_7ybpvzo9y2ve).

cueapi-core OSS substrate port is DEFERRED to a future sprint (Backlog row cmp2zi9tl001w04jxcxw3ank1 — 4-layer dependency stack: agent_live_sessions convergence → Surface 6 OSS → Lane 1 OSS → Layer 4 OSS). This PR ships the additive SDK surface in parallel so hosted-cueapi users get the new kwargs immediately.

Graceful degradation contract: hosted-cueapi accepts both new fields; cueapi-core OSS will 422 until precursors land. Docstrings cross-link Backlog row + flag the contract explicitly.

Wire shape

Kwarg Default Wire effect when omitted Wire effect when set
live_fallback_mode None field absent (server default: fallback_to_background) live_fallback_mode: <value> in body
parent_agent_id None field absent (BG agent — canonical default) parent_agent_id: <agt_xxx> in body

Tests (8 new across 2 files)

tests/test_messages_resource.py::TestLiveFallbackMode (3 tests):

  • omitted when None ⇒ absent on wire
  • "live_only" passes through
  • "fallback_to_background" passes through

tests/test_agents_resource.py::TestCreate (3 new in existing class):

  • omitted when None ⇒ absent on wire
  • "agt_bg_parent" passes through
  • combines cleanly with slug + webhook_url + display_name

Full unit suite (161 tests): all pass.

Companion artifacts

  • Backlog row cmp2zi9tl001w04jxcxw3ank1 updated 2026-05-13 ~00:32Z with explicit TRIGGER CONDITION (auto-pick-up when 3 OSS predecessors land) + LAST-VERIFIED EMPIRICAL STATE of cueapi-core (2 checks pinned for clean restart context). Future agent reading the row sees exactly what to verify before starting Layer 4 substrate port.

Out of scope

  • cueapi-cli --live-fallback-mode flag + --parent-agent-id flag — cueapi-three-2's lane
  • cueapi-mcp cueapi_send_message + cueapi_create_agent schema field additions — cueapi-three-2's lane
  • cueapi-action live-fallback-mode + parent-agent-id inputs — cueapi-three-2's lane

🤖 Generated with Claude Code

…args (cueapi #823 + #824 parity)

Agent-id-split refactor Layer 4 OSS-SDK additives. Hosted cueapi shipped
the substrate today (PR-A #823 schema + PR-B #824 router + PR-C #825
migration + #828 hotfix + PR-D #830 orphan-binding). cueapi-core OSS
substrate port is DEFERRED to a future sprint (Backlog row
cmp2zi9tl001w04jxcxw3ank1 — 4-layer dependency stack: agent_live_sessions
convergence → Surface 6 OSS → Lane 1 OSS → Layer 4 OSS); this PR ships
the additive SDK surface in parallel so hosted-cueapi users get the new
kwargs immediately. Graceful degradation: hosted accepts; cueapi-core
will 422 until precursors land.

## What ships

- **`MessagesResource.send(live_fallback_mode=None)`** — per-message
  override for substrate's Live-fallback semantic. `"live_only"` queues
  until target Live agent's session is heartbeating; `"fallback_to_background"`
  falls through to Live-sibling's BG parent (via parent_agent_id) when
  Live is silent. Default `None` omits the field from the wire body —
  server applies its default (`"fallback_to_background"` per spec lock
  22:11Z 2026-05-12).

- **`AgentsResource.create(parent_agent_id=None)`** — caller-supplied
  `agt_<12alpha>` linking the new agent to a BG parent. `None` = BG
  agent (default — canonical entry point for a project). Substrate
  enforces same-tenant + 1-level hierarchy. When supplied without
  explicit slug, substrate auto-derives `<parent_slug>-live` (collision-
  suffix on per-user duplicates).

Both kwargs are PURELY ADDITIVE — wire format identical to pre-Layer-4
callers when omitted. Docstrings cross-link the Backlog row + flag the
hosted-vs-cueapi-core graceful-degradation contract explicitly so SDK
users understand the OSS gap.

## Tests (8 new across 2 files)

`tests/test_messages_resource.py::TestLiveFallbackMode` (3 tests):
- live_fallback_mode omitted when None ⇒ field absent on wire
- live_fallback_mode="live_only" passes through verbatim
- live_fallback_mode="fallback_to_background" passes through verbatim

`tests/test_agents_resource.py::TestCreate` (3 new in existing class):
- parent_agent_id omitted when None ⇒ field absent on wire
- parent_agent_id="agt_bg_parent" passes through verbatim
- parent_agent_id combines cleanly with slug + webhook_url + display_name

Full unit suite (161 tests): all pass.

## Companion artifacts

- Backlog row cmp2zi9tl001w04jxcxw3ank1 updated 2026-05-13 ~00:32Z with
  explicit TRIGGER CONDITION (auto-pick-up when 3 OSS predecessors land)
  + LAST-VERIFIED EMPIRICAL STATE of cueapi-core (2 checks pinned for
  clean restart context). Future agent reading the row sees exactly what
  to verify before starting Layer 4 substrate port.

## cueapi-three-2 owns cli + mcp + action additives

This PR is the cueapi-python additive only. Per PM CTO call msg_8e7b5f47,
cli + mcp + action mirror additives are cueapi-three-2's lane. No overlap.
@govindkavaturi-art govindkavaturi-art enabled auto-merge (squash) May 13, 2026 00:31
@mikemolinet mikemolinet merged commit bd9b21b into main May 13, 2026
3 checks passed
@mikemolinet mikemolinet deleted the feat/sdk-live-fallback-mode-and-parent-agent-id branch May 13, 2026 00:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant